home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Hardware / Mac_OS_USB_DDK_v1.2 / Mac OS USB DDK Readme < prev    next >
Encoding:
Text File  |  1999-04-15  |  17.0 KB  |  445 lines  |  [TEXT/ttxt]
  1.  ***
  2.  ***       Universal Serial Bus(tm) (USB) for the Mac OS
  3.  ***    Mac OS USB 1.2 DDK Developer Release Notes
  4.  ***    Copyright 1998 Apple Computer, Inc.
  5.  ***
  6.  
  7.  
  8.  Table of Contents:
  9. -------------------------------------------------------------
  10.  Changes from USB v1.0, 1.0.1, 1.1 -> v1.2
  11.  USB Fundamentals
  12.  Keeping up to date on Mac OS USB
  13.  Getting started with Mac OS USB
  14.  Installing the Mac OS USB Software
  15.  Using the Mac OS USB DDK under MPW
  16.  Using the Mac OS USB DDK with MetroWerks CodeWarrior
  17.  Installing the Mac OS USB DDK for CodeWarrior for the First Time  
  18.  Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  19.  Using the CodeWarrior Project Files
  20.  Description of Installed Files
  21.  Known Problems and Issues
  22.  Contact Information
  23. -------------------------------------------------------------
  24.  
  25. Changes from USB v1.0, 1.0.1, 1.1 -> v1.2
  26. -------------------------------------------
  27.  
  28. Refer to the document "Mac OS USB v1.2 Readme" for a description
  29. of the changes between versions of USB. This DDK provides the Mac OS USB
  30. v1.2f7 interfaces and libraries which are the final versions. The DDK also
  31. includes the v1.2f7 System Extension components. The official Mac OS release
  32. of USB v1.2 will be through an updated version of the Mac OS ROM file.
  33. There will also be a final release of the Extension based components
  34. provided to Mac OS USB licensees to include with their USB PCI card
  35. products.
  36.  
  37.  
  38. System Requirements for USB 1.2
  39. ---------------------------------
  40.  
  41. Apple is formally qualifying USB 1.2 on iMac and Power Macintosh G3 systems
  42. with built-in USB support (and System 8.5.x installed). For iMac systems, 
  43. USB 1.1 must be present in the Mac OS ROM file in order for the USB v1.2
  44. system extension files to be recognized.
  45.  
  46.  
  47. USB Fundamentals
  48. ----------------
  49.  
  50. For the current generation of Power Macintosh systems, USB is the 
  51. primary interface for connections to low to medium speed peripheral
  52. devices. There are numerous advantages for adopting the USB standard on
  53. Macintosh, and they are discussed in the "Mac OS USB DDK API Reference
  54. Guide". On the future Macintosh systems there will be no ADB, 
  55. Serial Port, or SCSI connections. USB will be the primary port 
  56. for connecting peripheral devices to the Macintosh. 
  57.  
  58. The DDK provides the tools, interfaces, system files, and module 
  59. examples for you to start development of USB products
  60. for the Macintosh. The DDK provides the same release of USB
  61. component software that ships on the introductory release of the
  62. Power Macintosh iMac system.
  63.  
  64.  
  65. Keeping up to date on Mac OS USB
  66. --------------------------------
  67.  
  68. To stay abreast with developments on Mac OS USB, check out the 
  69. Mac OS USB Developer web site for the latest information. As updates
  70. to Mac OS USB occur, development releases of the software will be
  71. made available from this web site. The URL for the web site is:
  72.  
  73. <http://developer.apple.com/dev/usb>
  74.  
  75. You can also subscribe to the Mac OS USB Developer
  76. mailing list where development questions regarding Mac OS USB
  77. are posed and answered. To submit a question to the mailing list
  78. you must first be a subscriber. To subscribe to the mailing list,
  79. send an email with the subject field set to "subscribe usb" 
  80. (omit the double quotes for the message) to requests@isg.apple.com.
  81.  
  82. Use the following URL to accomplish this.
  83.  
  84. <mailto:requests@isg.apple.com?SUBJECT=subscribe usb>
  85.  
  86. USB Alerts to developers are always posted to the mailing list.
  87. These alerts are also posted to the Mac OS USB Developer Web
  88. site at the following location.
  89.  
  90. http://developer.apple.com/dev/usb/devalerts.html
  91.  
  92.  
  93. Getting started with Mac OS USB
  94. -------------------------------
  95.  
  96. To develop with Mac OS USB v1.1, you will need either an iMac or a Power
  97. Macintosh system with a USB PCI card installed.  For the iMac, you must
  98. have either System Software 8.5 present, or have installed at least the 
  99. iMac Update v1.0.
  100.  
  101. USB v1.1 will support PCI USB cards from several vendors, however the 
  102. Keyspan card has been extensively tested for compatibility with MacOS 
  103. 8.0, 8.1 & 8.5 and an the complete range of PCI-based Macintosh models.   
  104. This card includes USB v1.1 software on diskette, and Keyspan is prepared 
  105. to technical support to customers.
  106.  
  107.   http://www.keyspan.com/products/USB/
  108.  
  109. The enclosed software is for developmental purposes and will support USB 
  110. PCI cards from other vendors, but it is not directly supported by Apple, 
  111. nor is it intended for end-users. End-user customers are encouraged to 
  112. purchase a PCI USB card that includes licensed software and support.
  113.  
  114. You may find that development on a Power Mac system with a USB PCI card 
  115. and serial port, is easier, as you can use the Power Mac Debugger with a 
  116. second Power Macintosh system. A Power Macintosh system with ADB
  117. keyboard is useful for debugging with Macsbug, since there are cases when
  118. the system cannot process keystrokes from a USB keyboard.
  119.  
  120.  
  121. Installing the Mac OS USB Software
  122. ----------------------------------
  123.  
  124. Before using the enclosed software on an iMac or 1999 Power Macintosh G3, 
  125. you must already have the Mac OS USB v1.1 present. If the Mac OS ROM file 
  126. includes this release of USB, do not install the system extension 
  127. components from this DDK to the Extensions Folder.
  128.  
  129. To install the USB System Software components, 
  130. 1. remove all files with the following names from your Extensions Folder, 
  131.  
  132.      USB Support,
  133.   USB Device Extension,
  134.   USBCompositeDriver,
  135.   USBFamilyExpert,
  136.   USBHIDKeyboardModule,
  137.   USBHIDMouseModule,
  138.   USBHIDUniversalModule,
  139.   USBHubDriver0,
  140.   USBHubDriver1, and
  141.   USBOpenHCIDriver
  142.   USBPrintDriver
  143.   USBCommClass
  144.   SerialShimLib
  145.  
  146. 2. drag copy the contents of the folder
  147.  
  148. :USBDDK:Extensions-AppleBuilt: 
  149.  
  150. to the Extensions folder.
  151.  
  152. 3. Before you reboot, modify the file "USB Support" to include
  153. a new resource 'usbx' (Resource ID = 1984).  Without this resource, this release of
  154. USB will not load. The following alert is raised to indicate that the 
  155. resource is not present.
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169. 4. Reboot your system after making this modification.
  170.  
  171.  
  172. Important Notes on Installation and Use of this DDK software
  173. ------------------------------------------------------------
  174.  
  175. This DDK will let you look at the sources to some working class 
  176. drivers, build the examples, and develop & build your own code.
  177.  
  178. Please remember that these driver samples are Copyright Apple 
  179. Computer, Inc.. You may use the supplied code to develop Class 
  180. Drivers for your devices. As for publishing the source code, please
  181. check first with the Mac OS USB DDK License agreement, included
  182. in this DDK.
  183.  
  184. The current driver samples may, reflect the latest
  185. state of the art of driver writing for USB in the Mac OS. Note that
  186. the PrinterClassModule sample is for example
  187. purpose only. This sample is the basis for real
  188. drivers under development, however we are unable to provide
  189. the actual class driver code. The remaining examples are the
  190. real code for the Keyboard HID, Mouse HID, Universal HID, and 
  191. Composite class drivers which will ship on the iMac
  192.  
  193. While not extensively tested (by the development team), 
  194. the sample sources have been tweaked slightly to make builds 
  195. under CodeWarrior some what less problematic. The project files 
  196. are provided to help jumpstart your development process.
  197.  
  198.  
  199. Using the Mac OS USB DDK under MPW
  200. ----------------------------------
  201.  
  202. For previous releases of the USB DDK, we provided a current 
  203. UserStartup•USBDDK and makefiles for each of the sample class
  204. drivers. As there are very few developers who program
  205. with the MPW environment and to expidite the release of this 
  206. DDK, we will no provide make files for the class driver samples, 
  207. nor UserStartup files for MPW.
  208.  
  209. If MPW is your primary development platform and you need 
  210. a make file for one of the example class drivers, submit a 
  211. request to the Mac OS USB mailing list and a sample make file, if
  212. available for the example, will be sent to you. See the section
  213. "Keeping up to date on Mac OS USB" above for information on
  214. how to subscribe to the Mac OS USB Developer mailing list.
  215.  
  216.  
  217. Using the Mac OS USB DDK with MetroWerks CodeWarrior
  218. ---------------------------------------------------
  219.  
  220. We have supplied MetroWerks CodeWarrior project files for
  221. all of the USB Modules code examples. All of the project
  222. files were created using CodeWarrior Pro 1, IDE 2.0. The 
  223. project files are also compatible with CodeWarrior Pro IDE 
  224. 2.1, 3.0 and later.
  225.  
  226. For the CodeWarrior IDE environments v2.0 - v3.0, you must use
  227. the Universal Interface & Libraries v3.1. The examples will
  228. not build using the interfaces supplied with the CodeWarrior
  229. v.2 - v3.0 environments. The URL for the Developer Development
  230. Kits web page is
  231.    
  232.    <http://developer.apple.com/sdk/>
  233.  
  234. As mentioned for MPW, it is highly recommend that you use 
  235. one Macintosh for coding purposes and one Mac (aka "Target"
  236. system) for checkout/testing purposes.
  237.  
  238. The supplied project files will place the built drivers
  239. and extensions into the Target folder of the DDK.
  240.  
  241.  
  242. Installing the Mac OS USB DDK for CodeWarrior for the First Time
  243. -----------------------------------------------------------
  244.  
  245. 1. You can place the USBDDK anywhere on your development
  246.    system for the CodeWarrior environment. The access paths
  247.    for the project files are project and compiler relative.
  248.    If you move the examples folders out of the DDK, you must
  249.    fix the access paths so that the sources can be found.
  250.   
  251. 2. Ensure that the CodeWarrior IDE environment has at least the 
  252.    Universal Interfaces and Libraries 3.1 installed. The
  253.    download file from the DDK website includes instructions
  254.    for upgrading your CodeWarrior environment. Note that if
  255.    you upgrade your interfaces, you will also need to 
  256.    upgrade your precompiled headers. The supplied CodeWarrior
  257.    project files do not use precompiled headers.
  258.  
  259. 3. Copy the USB.h file included in this SDK to the 
  260.    ":Mac OS Support:Headers:Universal Headers:" folder.
  261.  
  262. 4. You will find that the project files will place the built drivers
  263.    and extensions into the folder.
  264.  
  265.     "USBDDK:Extensions-MCWBuilt"
  266.  
  267.    If this folder does not exist, or the folder name is different,
  268.    the class driver samples will be created in the CodeWarrior folder.
  269.  
  270. Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  271. -------------------------------------------------------------
  272.  
  273. 1. Copy the USB.h file included in this SDK to the 
  274.    ":Mac OS Support:Headers:Universal Headers:" folder. Do not
  275.    use the USB.h header file from an earlier USB DDK with the
  276.    supplied project files, as the examples may not build.
  277.  
  278. 2. If you experience compiler errors with the program samples,
  279.    check whether you have updated the USB.h header in the
  280.    ":Mac OS Support:Headers:Universal Headers:" folder.
  281.  
  282. 3. You will need to create a folder by the name
  283.  
  284.     "USBDDK:Extensions-MCWBuilt"
  285.  
  286.    If this folder does not exist, or the folder name is different,
  287.    the class driver samples will be created in the CodeWarrior folder.
  288.  
  289. Using the CodeWarrior Project Files
  290. ---------------------------------
  291.  
  292.    For the following samples, there is only a single target for 
  293.    each project:
  294.  
  295.    CompositeClassDriver
  296.    KeyboardModule
  297.    MouseModule
  298.    UniversalModule
  299.    USBKeypad
  300.    USBModem
  301.    USBTabletModule
  302.  
  303.    For the PrinterClassDriver example, compile the targets in 
  304.    the following order
  305.  
  306.   1. PrinterClassDRVR - creates the 68K DRVR resource
  307.   2. PrintClassDriver - creates the USB PrintClassDriver module
  308.   3. ChooserPack.rsrc - creates the "PACK" resource
  309.   4. USB Chooser Driver - creates the Chooser extension for the 
  310.      USB printer
  311.    
  312.    For the USBSampleStorageDriver example, compile the targets in 
  313.    the following order
  314.  
  315.   1. USBStorageClassDriver - creates the USB StorageClassDriver module
  316.   2. USBStorageClassShim - creates the shim module which loads the unit
  317.                            table driver when the device is attached
  318.      USBStorageClassUTDriver - auto built into shim - native driver
  319.                            compiled as a resource into shim file.   
  320.    
  321. Description of Installed Files
  322. --------------------------
  323. Files in the 'Extensions-AppleBuilt' folder:
  324. Files:                  Description:
  325. USB Device Extension    File which contains the following class drivers
  326.                         USBCompositeDriver - A class driver which is loaded for class 0
  327.                              & and subclass 0 devices (typically keyboards & mice, 
  328.                              although a few    printers & modems appear as composite 
  329.                              class devices).
  330.                                              USBHubDriver0 & USBHubDriver1 - The Hub driver for the root hub,
  331.                              the Apple USB keyboard's hub, and most 3rd party hubs.
  332.                         USBKeyboardModule - The HID Module loaded for a keyboard 
  333.                              interface (typically in a compound device)
  334.                         USBMouseModule - A HID Module loaded for a mouse interface 
  335.                              (typically in a compound device).
  336.                         USBHIDUniversalModule - A HID Module designed to support a
  337.                              number of 3rd party gaming devices via Game Sprockets. 
  338.                              Refer to the "Mac OS USB Compatibility Notes" for a 
  339.                              description of the game devices supported.
  340.                         USBOpenHCIDriver - The HAL (Hardware Abstraction Layer), also 
  341.                              known as the "UIM" (USB Interface Module). This driver 
  342.                              provides an abstracted interface to the OpenHCI host 
  343.                              controllers on Mac motherboards and PCI controller cards.                      
  344.  
  345. USB Support             The INIT (actually an 'expt') portion of the Family 
  346.                         Expert. Loaded prior to the INIT parade, it starts 
  347.                         the 'find a USB bus (i.e. UIM driver), loads the
  348.                         hub driver (for the root hub), and starts
  349.                         the hub driver running.  Once running, the
  350.                         hub driver locates devices attached to the
  351.                         port and asks the FamilyExpertLib to load
  352.                         drivers for the devices connected to the
  353.                         hub's ports.                            
  354.                             
  355. USBPrintDriver          A Printing Class Driver for experimentation
  356.                         purposes.  Printing WILL NOT be functional
  357.                         simply with the addition of this file.  The
  358.                         chooser extension needed for USB printing
  359.                         is still in development and has not yet
  360.                         been released.
  361.           
  362.     
  363. Known Issues
  364. ------------
  365.  
  366. The following is a list of known issues with this final release
  367. of the USB DDK.
  368.  
  369.   - If you install this release of USB 1.2f7 directly without adding
  370.     the 'usbx' (ID = 1984) resource, then USB will not load and an
  371.     alert message is displayed
  372.  
  373.     Refer to the instructions above in section "Installing the Mac 
  374.     OS USB Software" on how to modify the "USB Support" file so that 
  375.     it will function correctly.
  376.  
  377.   - The USBSampleStorageDriver does not correctly demonstrate how to
  378.     handle a hot unplug situation. This sample will be updated to 
  379.     demonstrate how this situation should be properly handled. The 
  380.     existing sample sets up a Timer Task which when fired makes a
  381.     call to SystemTask.  The call to SystemTask is not supported
  382.     from an interrupt context.
  383.  
  384. Contact Information
  385. -------------------
  386.  
  387.   Mac OS USB DDK Upgrades and latest information:
  388.     
  389.     Check the Developer Development Kits web page for
  390.         upgrades to the Mac OS USB DDK. The web page is
  391.         
  392.         <http://developer.apple.com/sdk/>
  393.  
  394.     For the latest information on Mac OS USB, check the Mac OS USB web page.
  395.     The web page is
  396.  
  397.     <http://usb.apple.com>
  398.  
  399.   For Bug Reports:
  400.  
  401.     To ensure the appropriate data is collected, please use the Bug Reporter  
  402.     to send us your bug reports. The Bug Reporter can be found at: 
  403.  
  404.     <http://developer.apple.com/bugreporter>
  405.  
  406.     When reporting problems, please include the machine configuration, 
  407.     including the vendor of the PCI USB card which you have tested with.
  408.  
  409.   For Technical Questions:
  410.  
  411.                 For generic Mac OS USB questions, submit them to the Mac OS USB 
  412.     Developer mailing list. Refer to the section above "Keeping up to date 
  413.     on Mac OS USB" for information on how to subscribe to this mailing list.
  414.     Often questions can be answered by someone on the mailing list.
  415.  
  416.  
  417.                 If your question is not answered on the mailing list, or if your question 
  418.     is proprietary, contact Worldwide Developer with purchased development-level 
  419.     technical support incidents at
  420.  
  421.     dts@apple.com
  422.  
  423.     Technical support incidents are bundled in our Premier and Select 
  424.     Developer programs. For information about joining our programs, 
  425.     please visit our Apple Developer Connection web site at 
  426.  
  427.     http://developer.apple.com/programs. 
  428.  
  429.     If you have never purchased a technical support incident and would like 
  430.     to find out how to do so, please visit the following site: 
  431.  
  432.     http://developer.apple.com/programs/techsupport.html . 
  433.  
  434.     
  435.   Comments, Suggestions and Enhancement Requests
  436.  
  437.     Please send all comments and suggestions regarding the Mac OS USB DDK to
  438.     
  439.     usb@apple.com
  440.  
  441.     All email sent to this address will be read, however, we will not be to
  442.     respond to all of your comments and suggestions.
  443.  
  444.         
  445.